استدعاء API في جوجل شيت

استدعاء واجهة برمجة تطبيقات API عامة في جداول بيانات جوجل باستخدام Apps Script

مقدمة

تُعد واجهات برمجة التطبيقات (APIs) أداة قوية تسمح للتطبيقات المختلفة بالتفاعل مع بعضها البعض ومشاركة البيانات. في عالم تطوير البرمجيات، تُستخدم هذه الواجهات للحصول على البيانات من خدمات مختلفة أو إرسالها إليها. إحدى المنصات التي توفر إمكانية استدعاء واجهات API بطريقة سهلة وفعالة هي جداول بيانات جوجل (Google Sheets). باستخدام Google Apps Script، يمكن للمستخدمين استدعاء واجهات برمجة التطبيقات العامة مباشرة داخل جداول بيانات جوجل وتحليل البيانات بطريقة مبتكرة.

في هذا المقال، سنتناول كيفية استخدام Google Apps Script لاستدعاء واجهات API العامة داخل جداول بيانات جوجل، وكيفية تخصيص هذه العمليات لتناسب احتياجات المستخدم المختلفة.

ما هو Google Apps Script؟

Google Apps Script هو بيئة تطوير مدمجة توفرها جوجل للمطورين لإنشاء تطبيقات وقوالب قابلة للتخصيص باستخدام جداول بيانات جوجل، مستندات جوجل، جداول بيانات جوجل وغيرها من خدمات جوجل. يُكتب Apps Script باستخدام لغة JavaScript ويُمكن للمستخدمين من توسيع وظائف التطبيقات عبر الإنترنت التي تقدمها جوجل، مثل Google Sheets وGoogle Docs وGmail.

خطوات استدعاء واجهة API عامة في جداول بيانات جوجل

1. إعداد Google Apps Script

أول خطوة تبدأ بها هي إعداد Google Apps Script داخل ملف جداول بيانات جوجل. للقيام بذلك، اتبع الخطوات التالية:

1. افتح جدول البيانات في جوجل الذي ترغب في ربطه بـ API.

2. اذهب إلى الأدوات ثم اختر محرر البرمجة.

3. في محرر البرمجة، سيتم فتح نافذة جديدة حيث يمكنك كتابة الأكواد البرمجية باستخدام Google Apps Script.

2. استدعاء واجهة API باستخدام الدالة UrlFetchApp

استدعاء واجهة برمجة التطبيقات (API) يتطلب إرسال طلب HTTP عبر الإنترنت. يمكن تنفيذ ذلك بسهولة باستخدام الدالة UrlFetchApp في Google Apps Script. هذه الدالة تُستخدم لإجراء طلبات HTTP (مثل GET أو POST) إلى واجهات API عبر الإنترنت.

فيما يلي نموذج بسيط لطلب HTTP GET لاستدعاء API عامة وإرجاع البيانات إلى جداول بيانات جوجل:

javascript
CopyEdit
function getAPIData() {
  var url = "https://api.example.com/data"; // استبدل هذا بعنوان API الفعلي
  var response = UrlFetchApp.fetch(url); // إرسال الطلب واستلام الاستجابة
  var json = JSON.parse(response.getContentText()); // تحويل النص المستلم إلى كائن JSON
  
  var sheet = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet(); // الحصول على الورقة الحالية
  var data = json.data; // استخدم المفتاح المناسب بناءً على بنية JSON للمحتوى المستلم
  
  // إدخال البيانات في جدول البيانات
  for (var i = 0; i < data.length; i++) {
    sheet.getRange(i + 1, 1).setValue(data[i].field1); // استبدال "field1" بمفتاح البيانات الفعلي
    sheet.getRange(i + 1, 2).setValue(data[i].field2); // استبدال "field2" بالمفتاح المناسب
  }
}

3. تحليل البيانات واستخراج المعلومات

بمجرد استدعاء البيانات من API، عادةً ما تكون البيانات في تنسيق JSON. لتحليل البيانات بشكل صحيح، يجب تحويل هذا التنسيق إلى كائن قابل للاستخدام في Google Apps Script.

في المثال أعلاه، تم استخدام JSON.parse() لتحويل البيانات المرسلة من API إلى هيكل بيانات يمكن التعامل معه في Google Apps Script. بعد التحويل، يمكن للمطورين الوصول إلى مختلف الحقول داخل كائن JSON واستخدامها في عمليات إضافية مثل إدخال البيانات في الخلايا المناسبة في جدول البيانات.

4. تخصيص الطلبات حسب الحاجة

بناءً على نوع API التي تستخدمها، قد تحتاج إلى إضافة معلمات إضافية في الطلب مثل المفاتيح API أو المعلمات المخصصة. على سبيل المثال، إذا كنت تتصل بـ API يتطلب مفتاح API، يمكنك إضافة هذا المفتاح إلى رأس الطلب أو كجزء من عنوان URL.

مثال على استخدام رأس طلب يحتوي على مفتاح API:

javascript
CopyEdit
function getAPIDataWithAPIKey() {
  var url = "https://api.example.com/data";
  var headers = {
    "Authorization": "Bearer YOUR_API_KEY" // استبدل "YOUR_API_KEY" بالمفتاح الفعلي
  };
  
  var options = {
    "method": "get",
    "headers": headers
  };
  
  var response = UrlFetchApp.fetch(url, options); // إرسال الطلب باستخدام الخيارات
  var json = JSON.parse(response.getContentText()); // تحليل البيانات
  
  // التعامل مع البيانات بالطريقة نفسها كما في المثال السابق
  var sheet = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet();
  var data = json.data;
  for (var i = 0; i < data.length; i++) {
    sheet.getRange(i + 1, 1).setValue(data[i].field1);
    sheet.getRange(i + 1, 2).setValue(data[i].field2);
  }
}

5. إضافة وظائف مخصصة مثل التكرار التلقائي

أحد الميزات الرائعة التي توفرها Google Apps Script هي القدرة على جدولة الوظائف لتعمل تلقائيًا في فترات زمنية محددة. هذا يمكن أن يكون مفيدًا للغاية إذا كنت ترغب في تحديث بيانات API بشكل دوري داخل جداول بيانات جوجل.

لإعداد تشغيل تلقائي (مثل تحديث البيانات كل ساعة)، يمكنك استخدام المشغلات التلقائية:

1. افتح محرر البرمجة.

2. اذهب إلى Edit ثم اختر Current project’s triggers.

3. اختر Add Trigger.

4. حدد الوظيفة التي تريد تشغيلها (مثل getAPIData)، ثم اختر توقيت التشغيل (مثل ساعة واحدة أو يوميا).

6. التعامل مع استجابة الأخطاء

عند العمل مع واجهات API، قد تواجه أخطاء في بعض الأحيان مثل انقطاع الاتصال أو استجابة غير صحيحة. لذلك، من المهم تضمين معالجة الأخطاء في الكود للتأكد من أن التطبيق لا يتوقف عن العمل بسبب هذه المشكلات.

إليك مثال على كيفية التعامل مع استجابة الأخطاء:

javascript
CopyEdit
function getAPIDataWithErrorHandling() {
  var url = "https://api.example.com/data";
  
  try {
    var response = UrlFetchApp.fetch(url); // إرسال الطلب
    var json = JSON.parse(response.getContentText()); // تحويل JSON
    
    var sheet = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet();
    var data = json.data;
    for (var i = 0; i < data.length; i++) {
      sheet.getRange(i + 1, 1).setValue(data[i].field1);
      sheet.getRange(i + 1, 2).setValue(data[i].field2);
    }
    
  } catch (error) {
    Logger.log("خطأ في استدعاء API: " + error.message); // تسجيل الخطأ
  }
}

الخاتمة

من خلال استخدام Google Apps Script، يمكن للمطورين استدعاء واجهات برمجة التطبيقات العامة داخل جداول بيانات جوجل بشكل مرن وسهل. تقدم Google Apps Script العديد من الإمكانيات التي تساعد في تخصيص استدعاء API، تحليل البيانات المستلمة، وتخزينها في جداول البيانات. كما أن إضافة معالجات الأخطاء والقدرة على جدولة الوظائف التلقائية تجعل هذا الحل أكثر قوة وملائمة للعديد من الاستخدامات.